icontheme: Clarify GENERIC_FALLBACK flag handling

- Add docs explaining that it doesn't work everywhere
- g_warn_if_fail() in the APIs where it doesn't work

diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index 59e99fc6f75d4e5b17c19abde7e24aba9eb1cf8d..eb89bf4cd6eac555be281889796d854e60958370 100644 (file)
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -2155,6 +2155,7 @@ gtk_icon_theme_choose_icon (GtkIconTheme       *icon_theme,
   g_return_val_if_fail (icon_names != NULL, NULL);
   g_return_val_if_fail ((flags & GTK_ICON_LOOKUP_NO_SVG) == 0 ||
                         (flags & GTK_ICON_LOOKUP_FORCE_SVG) == 0, NULL);
+  g_warn_if_fail ((flags & GTK_ICON_LOOKUP_GENERIC_FALLBACK) == 0);
 
   return choose_icon (icon_theme, icon_names, size, 1, flags);
 }
@@ -2196,6 +2197,7 @@ gtk_icon_theme_choose_icon_for_scale (GtkIconTheme       *icon_theme,
   g_return_val_if_fail ((flags & GTK_ICON_LOOKUP_NO_SVG) == 0 ||
                         (flags & GTK_ICON_LOOKUP_FORCE_SVG) == 0, NULL);
   g_return_val_if_fail (scale >= 1, NULL);
+  g_warn_if_fail ((flags & GTK_ICON_LOOKUP_GENERIC_FALLBACK) == 0);
 
   return choose_icon (icon_theme, icon_names, size, scale, flags);
 }
@@ -5423,6 +5425,7 @@ gtk_icon_theme_lookup_by_gicon_for_scale (GtkIconTheme       *icon_theme,
 
   g_return_val_if_fail (GTK_IS_ICON_THEME (icon_theme), NULL);
   g_return_val_if_fail (G_IS_ICON (icon), NULL);
+  g_warn_if_fail ((flags & GTK_ICON_LOOKUP_GENERIC_FALLBACK) == 0);
 
   if (GDK_IS_PIXBUF (icon))
     {

diff --git a/gtk/gtkicontheme.h b/gtk/gtkicontheme.h
index e57c95c3dd19d07dc4c758cc4e0af8f163e3d12f..7824a46765b36f41a05e19efcb2c72ed0b2a0ccd 100644 (file)
--- a/gtk/gtkicontheme.h
+++ b/gtk/gtkicontheme.h
@@ -109,7 +109,8 @@ struct _GtkIconThemeClass
  *   as well as files. For a builtin icon, gtk_icon_info_get_filename()
  *   is %NULL and you need to call gtk_icon_info_get_builtin_pixbuf().
  * @GTK_ICON_LOOKUP_GENERIC_FALLBACK: Try to shorten icon name at '-'
- *   characters before looking at inherited themes. For more general
+ *   characters before looking at inherited themes. This flag is only
+ *   supported in functions that take a single icon name. For more general
  *   fallback, see gtk_icon_theme_choose_icon(). Since 2.12.
  * @GTK_ICON_LOOKUP_FORCE_SIZE: Always get the icon scaled to the
  *   requested size. Since 2.14.